home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2004 #2 / Amiga Plus CD - 2004 - No. 02.iso / AmiSoft / Dev / lang / amigatalk.lha / help / boopsidocs / layout_gc.doc < prev    next >
Text File  |  1999-10-30  |  34KB  |  856 lines
  1. TABLE OF CONTENTS
  2.  
  3. layout_gc/--datasheet--
  4. layout_gc/ActivateLayoutGadget
  5. layout_gc/FlushLayoutDomainCache
  6. layout_gc/LAYOUT_GetClass
  7. layout_gc/LayoutLimits
  8. layout_gc/RethinkLayout
  9. layout_gc/--datasheet--                               layout_gc/--datasheet--
  10.  
  11.     NAME
  12.         layout.gadget-- An automatic GUI layout arrangement gadget.
  13.  
  14.     SUPERCLASS
  15.         gadgetclass
  16.  
  17.     REQUIRES
  18.         bevel.image
  19.  
  20.     DESCRIPTION
  21.         The layout gadget is used to automatically calculate the
  22.         positions and sizes of BOOPSI gadgets and images in a resizable
  23.         window. Instead of handling the positions of gadgets by hand,
  24.         you can just describe your window layout in a hierarchical
  25.         fashion, and the layout gadget will do the rest.
  26.  
  27.         The basic method of layout of a group is as follows:
  28.         - Calculate the minimum and maximum size of each gadget.
  29.         - Calculate the weight totals for the group. Substract the size
  30.           of the fixed size (weighted size 0) gadgets from the total
  31.           size of the group.
  32.         - Distribute the remaining space in the group according to the
  33.           relative weighs of the children.
  34.         - If extra space remains, distribute it evenly between the
  35.           children.
  36.  
  37.     PRIVATE METHODS
  38.         LAYOUT_ACTIVATEOBJECT -- Used by ActivateLayoutGadget(), sets
  39.         the handleinput path to a gadget somewhere in a layout hierarchy.
  40.         
  41.         LAYOUT_TABCYCLE -- Sets the gadget attributes based on the 
  42.         gadget in the end of the handleinput path.
  43.         
  44.         LAYOUT_FIRSTCYCLE -- Sets the handleinput path to the first tab
  45.         cycle gadget in a layout hierarchy.
  46.  
  47.         LAYOUT_LASTCYCLE -- Sets the handleinput path to the last tab
  48.         cycle gadget in a layout hierarchy.
  49.  
  50.         LAYOUT_FLUSHDOMAINS -- Flushes all domain caches below a certain
  51.         level.
  52.         
  53.         LAYOUT_FINDKEY -- Find a gadget with a key in the CommKey list.
  54.         
  55.         LAYOUT_FINDACTIVE -- Find the active gadget pointer.
  56.         
  57.         LAYOUT_FINDHELP -- Find the last gadget that returned helphit.
  58.  
  59.     METHODS
  60.         GM_HANDLEINPUT -- Passed to the currently active child
  61.  
  62.         GM_DOMAIN -- Passed to all children
  63.  
  64.         GM_RENDER -- Passed to all children When invoked
  65.             by input.device, the stack is first swapped to provide
  66.             more workspace.
  67.  
  68.         GM_LAYOUT -- Passed to all children after first setting
  69.             their size and position with SetAttrs. When invoked
  70.             by input.device, the stack is first swapped to provide
  71.             more workspace.
  72.  
  73.         GM_HITTEST -- Passed to the child in whose domain
  74.             rectangle the pointer is
  75.  
  76.         GM_HELPTEST -- Passed to the child in whose domain
  77.             rectangle the pointer is
  78.  
  79.         GM_GOACTIVE -- Passed to the currently "active" child (one
  80.             that returned GM_HITTEST)
  81.  
  82.         GM_GOINACTIVE -- Passed to the currently active child
  83.  
  84.         OM_SET -- Passed to superclass after scanning the
  85.             taglist for layout specific tags
  86.  
  87.         OM_UPDATE -- Passed to superclass after scanning the
  88.             taglist for layout specific tags
  89.  
  90.         OM_GET -- Passed to superclass for non-layout tags
  91.  
  92.         OM_NEW -- Passed to superclass, then adding all the
  93.             children on the taglist to the private list.
  94.  
  95.         OM_DISPOSE -- Passed to all children (thus disposing all
  96.             of them), then to superclass.
  97.             
  98.         GM_CLIPRECT -- Passed to all children.
  99.         
  100.         DTM_PROCLAYOUT -- Like GM_LAYOUT, but passes DTM_PROCLAYOUT
  101.             forward. Useful if the layout group contains only
  102.             datatype objects.
  103.  
  104.         All other methods are passed to the superclass.
  105.  
  106.   ATTRIBUTES
  107.       Attributes global to the whole layout group. Pass all of these 
  108.       BEFORE adding child objects:
  109.       
  110.       GA_ReadOnly (BOOL)
  111.           Disables input to the entire layout group and its chidren.
  112.           This tag is NOT propagated to children. The input blocking
  113.           occurs within the layout object itself.
  114.  
  115.           Defaults to FALSE
  116.           
  117.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)             
  118.  
  119.       GA_Disabled (BOOL)
  120.           Disables entire layout group and its chidren. This tag
  121.           is propagated all children. When setting/clearing this
  122.           tag, take care to re-set/re-clear any children you want
  123.           included from this mass disabling ability.
  124.  
  125.           Defaults to FALSE
  126.           
  127.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)             
  128.  
  129.       GA_TextAttr (struct TextAttr *)
  130.           The font that will be used for the group label.
  131.           
  132.           Defaults to NULL (uses rastport default font).
  133.           
  134.           Applicability is (OM_NEW)
  135.              
  136.       LAYOUT_Orientation (ULONG)
  137.           Whether the objects of this group are arranged horizontally or
  138.           vertically. Possible values are LORIENT_HORIZONTAL and
  139.           LORIENT_VERTICAL.
  140.  
  141.           Defaults to LORIENT_HORIZONTAL.
  142.  
  143.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  144.  
  145.       LAYOUT_FixedHoriz (BOOL)
  146.           Whether the width of this layout group is fixed to the width
  147.           assigned by the window or parent layout group. If set to FALSE,
  148.           the gadget will minimize its width to the smallest possible
  149.           value. Generally you will have to also set LAYOUT_ShrinkWrap
  150.           (below) to TRUE also. It is recommended that this tag is used
  151.           only in the top layout group. Using a weighted width of 0 gives
  152.           more predictable results elsewhere.
  153.  
  154.           Defaults to TRUE.
  155.  
  156.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  157.  
  158.       LAYOUT_FixedVert (BOOL)
  159.           Whether the height of this layout group is fixed to the height
  160.           assigned by the window or parent layout group. If set to FALSE,
  161.           the gadget will minimize its height to the smallest possible
  162.           value. Generally you will have to also set LAYOUT_ShrinkWrap
  163.           (below) to TRUE also. It is recommended that this tag is used
  164.           only in the top layout group. Using a weighted height of 0 gives
  165.           more predictable results elsewhere.
  166.  
  167.           Defaults to TRUE.
  168.  
  169.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  170.  
  171.       LAYOUT_HorizAlignment (ULONG)
  172.           The horizontal alignment of the objects in this layout group.
  173.           Possible values are LALIGN_LEFT, LALIGN_RIGHT, and 
  174.           LALIGN_CENTER.
  175.  
  176.           Defaults to LALIGN_LEFT.
  177.  
  178.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  179.  
  180.       LAYOUT_VertAlignment (ULONG)
  181.           The vertical alignment of the objects in this layout group.
  182.           Possible values are LALIGN_TOP, LALIGN_BOTTOM, and 
  183.           LALIGN_CENTER.
  184.  
  185.           Defaults to LALIGN_TOP.
  186.  
  187.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  188.  
  189.       LAYOUT_ShrinkWrap (BOOL)
  190.           If set to TRUE, the layout group will shrink the interspacing
  191.           of the child objects to minimum. Normally all extra space (if
  192.           the total maximum size of the child objects is less than the
  193.           size of the layoutgroup) is evenly distributed between the
  194.           gadgets.
  195.  
  196.           Defaults to FALSE.
  197.  
  198.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  199.  
  200.       LAYOUT_EvenSize (BOOL)
  201.           If TRUE, the layout group will try to reserve enough space to
  202.           make the minimum size of each child object equal to the minimum
  203.           of the largest child. Using this attribute makes it possible to
  204.           have neatly arranged horizontal rows or grids of gadgets. This
  205.           can take quite a bit of room, however, depending on the gadgets.
  206.  
  207.           Defaults to FALSE.
  208.  
  209.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  210.           
  211.       LAYOUT_SpaceInner (BOOL)
  212.          Should layout leave space between objects or not. Set to FALSE
  213.          if objects in a group should be put immediately beside each 
  214.          other.
  215.          
  216.          Defaults to TRUE.
  217.          
  218.          Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  219.              
  220.       LAYOUT_SpaceOuter (BOOL)
  221.          Should layout leave space around the group's objects or not. 
  222.          Set to TRUE if the objects should not be laid out using the 
  223.          whole group container box (for example if the group has a 
  224.          bevel around it).
  225.          
  226.          Defaults to FALSE.
  227.          
  228.          Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  229.              
  230.       LAYOUT_InnerSpacing (ULONG)
  231.           The minimum space left between objects. The value is in "virtual
  232.           pixels", ie absolute pixels assuming bevel is configured for
  233.           thin lines. If bevel configuration is something else, the value 
  234.           will be adjusted accordingly.
  235.  
  236.           Please avoid using this tag, if you do not require absolute 
  237.           control over the spacing. The LAYOUT_SpaceInner boolean is
  238.           provided to tell whether there should be spacing or whether
  239.           objects should be immediately connected to each other.
  240.  
  241.           Defaults to INTERSPACING.
  242.  
  243.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  244.  
  245.       LAYOUT_TopSpacing
  246.       LAYOUT_BottomSpacing
  247.       LAYOUT_LeftSpacing
  248.       LAYOUT_RightSpacing (ULONG)
  249.           The minimum space left to the top, bottom, left and right of
  250.           the group, respectively. This value is in "virtual pixels", see
  251.           LAYOUT_Spacing above.
  252.  
  253.           Please avoid using this tag, if you do not require absolute 
  254.           control over the spacing. The LAYOUT_SpaceOuter boolean is
  255.           provided to tell whether there should be spacing or whether
  256.           objects should be immediately connected to each other.
  257.           
  258.           If you use one of these tags to override a LAYOUT_SpaceOuter,
  259.           pass this tag AFTER the LAYOUT_SpaceOuter tag.
  260.  
  261.           Defaults to 0.
  262.  
  263.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  264.  
  265.       LAYOUT_BevelStyle (ULONG)
  266.           The style of the bevel drawn around the group. This value is
  267.           passed to bevel.image.
  268.  
  269.           Defaults to BVS_NONE.
  270.  
  271.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  272.  
  273.       LAYOUT_BevelState (ULONG)
  274.           The state of the bevel drawn around the group. Used to
  275.           DrawImageState() the bevel.image.
  276.  
  277.           Defaults to IDS_NORMAL.
  278.  
  279.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  280.  
  281.       LAYOUT_Label (STRPTR)
  282.           The label drawn in the group bevel. This value is passed to
  283.           bevel.image. Note that if LAYOUT_BevelStyle is set to BVS_NONE,
  284.           no bevel will be rendered, and thus this label will not be used
  285.           either.
  286.  
  287.           No default (bevel.image default used)
  288.  
  289.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  290.  
  291.       LAYOUT_LabelImage (Object *)
  292.           The BOOPSI image to use as the group bevel label. Passed to
  293.           bevel.image.
  294.  
  295.           See LAYOUT_Label.
  296.  
  297.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  298.  
  299.       LAYOUT_LabelPlace (ULONG)
  300.           The position of the label (See LAYOUT_Label).
  301.  
  302.           Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  303.  
  304.       LAYOUT_RemoveChild (Object *)
  305.           Pointer to an object you wish to remove from the layout
  306.           hierarchy. The object will be disposed of, so after using this
  307.           tag, the pointer will be invalid.
  308.  
  309.           Applicability is (OM_SET)
  310.  
  311.       LAYOUT_AddChild (Object *)
  312.           Pointer to an object you wish to add to the list of gadgets for
  313.           this layout hierarchy level.
  314.  
  315.           Applicability is (OM_NEW)
  316.  
  317.       LAYOUT_AddImage (Object *)
  318.           Same as LAYOUT_AddChild, but will mark the object as an
  319.           imageclass subclass (meaning that IM_DRAW will be used instead
  320.           of GM_RENDER to display it, and that none of the gadgetclass
  321.           methods apply to it).
  322.  
  323.           Applicability is (OM_NEW)
  324.  
  325.       LAYOUT_ModifyChild (Object *)
  326.           Inform layout gadget that the following child specific tags in
  327.           the taglist apply to the specified object. LAYOUT_AddChild will
  328.           do this automatically for new objects.
  329.  
  330.           Applicability is (OM_SET)
  331.  
  332.       LAYOUT_RelVerify (BOOL)
  333.           When a gadget returns a code that normally makes Intuition send
  334.           an IDCMP_GADGETUP message to the application, layout.gadget
  335.           will send a notification message (OM_NOTIFY, IDCMP_IDCMPUPDATE)
  336.           with the essential information of the gadgetup message. This is
  337.           because in certain situations the IDCMP_GADGETUP message can
  338.           not be sent (in particular, when tab cycling between gadgets).
  339.           The notification will consist of GA_ID set to the ID of the
  340.           gadget in question, this LAYOUT_RelVerify tag set to TRUE, and
  341.           the LAYOUT_RelCode tag (below) set to the gadget's return code
  342.           (IntuiMessage.Code field of the IDCMP_GADGETUP).
  343.  
  344.           Applicability is (OM_NOTIFY)
  345.  
  346.       LAYOUT_RelCode (UWORD)
  347.           A copy of the IntuiMessage.Code field of the IDCMP_GADGETUP in
  348.           question, sent via OM_NOTIFY (ie. received as OM_UPDATE or
  349.           IDCMP_IDCMPUPDATE).
  350.  
  351.           Applicability is (OM_NOTIFY)
  352.           
  353.       LAYOUT_TabVerify (BOOL)
  354.           If the gadget release was triggered by tab cycling, this 
  355.           attribute will be TRUE in the release verify IDCMPUPDATE. This 
  356.           lets you distinguish, for example, between pressing tab and
  357.           enter in a string gadget.
  358.           
  359.           Applicability is (OM_NOTIFY)
  360.              
  361.       LAYOUT_RelAddress (struct Gadget *)
  362.           Address of the gadget that sent the gadgetup is provided in the
  363.           gadgetup notification using this tag.
  364.           
  365.           Applicability is (OM_NOTIFY)
  366.              
  367.       LAYOUT_HelpHit (UWORD)
  368.           When a gadget returns a hit for helptest, the return code, along
  369.  
  370.           with GA_ID, is notified using this tag.
  371.           
  372.           Applicability is (OM_NOTIFY)
  373.  
  374.       LAYOUT_Parent (Object *)
  375.           Set automatically by layout.gadget for all child objects, this
  376.           attribute points to the parent layout object. If NULL, the 
  377.           layout object is the window's topmost layout.
  378.           When an object is added to the layout hierarchy, it will
  379.           receive this tag in OM_SET. If you so wish, you may use this to
  380.           let the gadget talk to its parent layout group.
  381.           Any group gadget that should work with layout.gadget must 
  382.           support this attribute.
  383.  
  384.           Applicability is (OM_SET, OM_GET)
  385.  
  386.       LAYOUT_DeferLayout (BOOL)
  387.           By setting this tag to TRUE in your window's top layout, you 
  388.           can defer the layout and refresh process off the input.device 
  389.           context to your application. This will make input.device more 
  390.           responsive, and drop the (possibly quite heavy) process of 
  391.           recalculating the display to normal application priority 
  392.           instead of the priority 20
  393.           of input.device. Input handling will be retained in input.device
  394.           context, to keep the GUI responsive.
  395.           If you use this tag, you must listen to LAYOUT_RequestLayout 
  396.           and LAYOUT_RequestRefresh notifications and process them in 
  397.           prompt manner, or your GUI will not display properly, if at all.
  398.  
  399.           Applicability is (OM_NEW, OM_SET)
  400.  
  401.       LAYOUT_RequestLayout (Object *)
  402.           If the above LAYOUT_DeferLayout tag is set to TRUE, the gadget 
  403.           will defer GM_LAYOUT methods invoked by input.device and notify 
  404.           its IC target with this tag. You should be listening to it in 
  405.           your application IDCMP handler (IDCMP_IDCMPUPDATE) and calling
  406.           RethinkLayout with FALSE for refresh flag when receiving one.
  407.  
  408.           Defaults to FALSE.
  409.  
  410.           Applicability is (OM_NOTIFY)
  411.  
  412.       LAYOUT_RequestRefresh (Object *)
  413.           If the above LAYOUT_DeferLayout tag is set to TRUE, the gadget 
  414.           will defer GM_RENDER methods invoked by input.device and notify 
  415.           its IC target with this tag. You should be listening to it in 
  416.           your application IDCMP handler (IDCMP_IDCMPUPDATE) and calling
  417.           RefreshGList when receiving one.
  418.  
  419.           Defaults to FALSE.
  420.  
  421.           Applicability is (OM_NOTIFY)
  422.           
  423.       LAYOUT_TextPen (WORD)
  424.           The pen that will be used for group label text. See bevel.image.
  425.           
  426.           Applicability is (OM_NEW)
  427.           
  428.       LAYOUT_FillPen (WORD)
  429.           The pen that will be used for the group fill pattern. See 
  430.           bevel.image.
  431.           
  432.           Applicability is (OM_NEW)
  433.           
  434.       LAYOUT_FillPattern (UWORD *)
  435.           The fill pattern for the group. See bevel.image.
  436.           
  437.           Defaults to none.
  438.           
  439.           Applicability is (OM_NEW)
  440.           
  441.       GA_BackFill (struct Hook *)
  442.           A layer backfill hook to use in the group to provide a more
  443.           complex background pattern.
  444.           
  445.           Defaults to clear for the main layout, and none for sublayouts.
  446.           
  447.           Applicability is (OM_NEW)
  448.           
  449.       LAYOUT_LabelColumn (ULONG)
  450.           The side where the on which side of the gadget the label will
  451.           be placed in the group. Valid values are PLACETEXT_LEFT and 
  452.           PLACETEXT_RIGHT. See CHILD_Label.
  453.           
  454.           Defaults to PLACETEXT_LEFT.
  455.           
  456.           Applicability is (OM_NEW, OM_SET, OM_NOTIFY)
  457.           
  458.       LAYOUT_LabelWidth (ULONG)
  459.           The width of the label column in a vertical group. This attribute
  460.           may be used to justify several layout groups.
  461.           
  462.           Applicability is (OM_SET, OM_GET)
  463.           
  464.       LAYOUT_AlignLabels (Object *)
  465.           A pointer to another layout instance that should have equal 
  466.           label width with this one. Set to a cycle between all the 
  467.           groups, these will automatically justify their labels with each 
  468.           other. This attribute should be set as soon as possible, ie. in 
  469.           OM_NEW or OM_SET directly afterwards, before the layout size is 
  470.           calculated.
  471.           
  472.           Applicability is (OM_NEW, OM_SET)
  473.  
  474.       LAYOUT_Inversed (BOOL) (V42.27)
  475.           Causes children to be added to the layout group via
  476.           AddHead() vs AddTail(). 
  477.           
  478.           Applicability is (OM_NET, OM_SET)
  479.           
  480.  
  481.       Attributes referring to the "current" child object:
  482.  
  483.       CHILD_MinWidth, CHILD_MinHeight (ULONG)
  484.           The minimum width and height of the object, in pixels. Setting 
  485.           this attribute means that GM_DOMAIN is not respected in that 
  486.           direction.
  487.  
  488.           Defaults to ~0, which means that the layout gadget will ask the
  489.           object, using GM_DOMAIN.
  490.  
  491.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  492.  
  493.       CHILD_MaxWidth, CHILD_MaxHeight (ULONG)
  494.           As above, for the maximum size.
  495.  
  496.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  497.  
  498.       CHILD_NominalSize (BOOL)
  499.           If this attribute is TRUE, layout will use GDOMAIN_NOMINAL
  500.           instead of GDOMAIN_MINIMUM when requesting the minimum size of
  501.           the gadget. This is useful when the minimum size of a gadget
  502.           looks unattractive, but the gadget will return a more attractive
  503.           size with GDOMAIN_NOMINAL.
  504.  
  505.           Defaults to FALSE.
  506.  
  507.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  508.  
  509.       CHILD_WeightedWidth (ULONG)
  510.           The relative width of the child object. See the DESCRIPTION
  511.           above for the layout method. If set to 0, the child will always
  512.           be rendered in the minimum size (specified by either GM_DOMAIN
  513.           or CHILD_MinWidth). Use CHILD_MinWidth and a weighted with of 0
  514.           instead of CHILD_MinWidth and CHILD_MaxWidth. The latter method
  515.           will also work, but will slow down the layout. As a special
  516.           rule, many BOOPSI images using bitmap data can not be resized
  517.           from the initial size. Fix their size by setting MinWidth and
  518.           MinHeight, and the weight to 0.
  519.  
  520.           Defaults to 100.
  521.  
  522.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  523.  
  524.       CHILD_WeightedHeight (ULONG)
  525.           The relative height of the child object. See CHILD_WeightedWidth.
  526.  
  527.           Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  528.  
  529.       CHILD_WeightMinimum (BOOL)
  530.           Setting this tag to TRUE will make the layout group set the
  531.           weighted width and height to the minimum values set with
  532.           CHILD_MinWidth and CHILD_MinHeight or returned by GM_DOMAIN. This
  533.           allows creating layout groups where the relative size of the
  534.           objects always remains the same. Be warned that if the object 
  535.           does not support GM_DOMAIN and minimum size is not set manually, 
  536.           the weight will be set to 2 (the default minimum size of an 
  537.           object). Normally you would want to set this tag for every 
  538.           resizable object in a layout group.
  539.  
  540.           Defaults to FALSE.
  541.  
  542.           Applicability is (OM_NEW)
  543.  
  544.       CHILD_ReplaceObject
  545.           CHILD_ReplaceImage (Object *)
  546.           Replace the current child object with the one specified. The
  547.           current object will be disposed of. See LAYOUT_AddChild,
  548.           LAYOUT_AddImage, LAYOUT_RemoveChild, LAYOUT_ModifyChild.
  549.  
  550.           Applicability is (OM_SET)
  551.  
  552.       CHILD_CacheDomain (BOOL)
  553.           To speed up resizing, layout gadget will normally cache the
  554.           first values returned by GM_DOMAIN and use that cache for
  555.           subsequent relayouts, instead of calling GM_DOMAIN again.
  556.           Normally this will have the same results all the time. If you
  557.           have a custom gadget that might return varying values between
  558.           calls to GM_DOMAIN (ie the minimum or maximum size of it could
  559.           vary during runtime), set this tag to FALSE for that object and
  560.           all its parent groups. Note that since layout groups are aware
  561.           of their parent layouts, they can disable caching in the
  562.           hierarchy above them automatically,  if you SetAttr this
  563.           attribute _AFTER_ creating the whole layout hierarchy.
  564.  
  565.           Defaults to TRUE.
  566.  
  567.           Applicability is (OM_NEW, OM_SET) (OM_SET preferred)
  568.           
  569.       CHILD_Label (Object *)
  570.           The imageclass object, preferably label.image, to use as the 
  571.           object's label. These labels are supported only left or right 
  572.           aligned groups, and will be placed in the left or right of the 
  573.           gadget even in horizontal groups. All the labels will take the
  574.           space of the widest label. Label-less objects will be laid out 
  575.           in full width; if you want to leave the label column empty, use 
  576.           the special value LCLABEL_NOLABEL. Every object in a group gets
  577.           the same amount of space reserved for a label, whether they have
  578.           a label or not. This also (or in particular) applies to
  579.           horizontal groups; usually the correct effect is reached by
  580.           putting the label on the group itself instead of one of the
  581.           objects in it. See LAYOUT_LabelColumn.
  582.           
  583.           Defaults to NULL.
  584.           
  585.           Applicability is (OM_NEW, OM_SET)
  586.           
  587.       CHILD_NoDispose (BOOL)
  588.           By setting this attribute, you inform the layout object that
  589.           this child object should not be automatically disposed when
  590.           the layout object itself is disposed. This attribute allows
  591.           sharing objects between layouts.
  592.           
  593.           Default is FALSE.
  594.           
  595.           Applicability is (OM_NEW, OM_SET)
  596.  
  597.       CHILD_ScaledWidth (UWORD) (V42.27)
  598.           Scales the child minimum domain size to a larger value;
  599.  
  600.           minwidth = minwidth + ((minsize * scalewidth)/100)
  601.           
  602.           Default is 0.
  603.           
  604.           Applicability is (OM_NEW, OM_SET)
  605.  
  606.       CHILD_ScaledHeight (UWORD) (V42.27)
  607.           Scales the child minimum domain size to a larger value;
  608.  
  609.           minheight = minheight + ((minsize * scaleheight)/100)
  610.           
  611.           Default is 0.
  612.           
  613.           Applicability is (OM_NEW, OM_SET)
  614.  
  615.   NOTES
  616.       Setting the attributes via SetGadgetAttrs() (OM_SET) will not
  617.       automatically rerender the display! Call RethinkLayout() to
  618.       relayout and refresh display after SetGadgetAttrs().
  619.  
  620.       In this document, the terms layout, group, and object are used
  621.       intermixed. Most of the time, layout and group are used as
  622.       synonyms. Virtually any object referred to could also be a
  623.       layout group.
  624.  
  625.       To make defining layout hierarchies easier, the reaction_macros.h
  626.       include file defines a set of macros that hide NewObject()
  627.       calls. This will clean up the rather large tag lists for the
  628.       creation of layout groups. See the ReAction examples for use of
  629.       these macros, and layout.gadget in general.
  630.  
  631.       In relation to above, remember that in AmigaOS (as of V40), the
  632.       stack size is restricted. During the beta test period, the
  633.       average size of a layout group for a whole window seemed to
  634.       average at approximately 1 KB. Building as large tag lists as
  635.       this on stack is rather slow, as well as easily overflowing the
  636.       small default stacks of AmigaOS. For windows with relatively
  637.       static layouts that are opened often, consider building tag
  638.       lists as static data and passing a pointer to them for
  639.       NewObjectA(). If this is too much work, make sure that your
  640.       program's stack is large enough to hold  the tag list. If it is
  641.       too small, you can use the V37 Exec StackSwap() call to replace
  642.       it with a larger one, or simply set the global variable long
  643.       __stack to a large enough value, if the startup code you link
  644.       with provides stack swap support, as for example the c.o of
  645.       SAS/C 5.x and above does.
  646.  
  647.       Due to Intuition limitations, IDCMP_GADGETUP messages are not
  648.       fully supported. The IAddress will always point to the root
  649.       layout object of the window, not the actual gadget the message
  650.       originates from. Use GadgetID to distinguish between gadgets.
  651.       When using tab cycle, GADGETUP messages will be lost
  652.       altogether. However, layout.gadget sends a notification for all
  653.       gadgetups, containing the tags GA_ID, LAYOUT_RelVerify and
  654.       LAYOUT_RelCode, containing, respectively, the ID, TRUE, and the
  655.       IntuiMessage.Code value it returned. Additionally a 
  656.       LAYOUT_TabVerify tag will be TRUE or FALSE depending on whether
  657.       the gadget release was triggered by tab cycle.
  658.       Use of models and/or IDCMP_IDCMPUPDATE is encouraged.
  659.  
  660.   SEE ALSO
  661.       ReAction example source for usage.
  662. layout_gc/ActivateLayoutGadget                 layout_gc/ActivateLayoutGadget
  663.  
  664.   NAME
  665.       ActivateLayoutGadget -- Activate a gadget within a layout window.
  666.  
  667.   SYNOPSIS
  668.       Success = ActivateLayoutGadget( Gadget, Window, Request, Object )
  669.       d0                              a0      a1      a2       d0
  670.  
  671.       BOOL ActivateLayoutGadget( struct Gadget *, struct Window *,
  672.               struct Requester *, ULONG );
  673.  
  674.   FUNCTION
  675.       The equivalent of intuition.library ActivateGadget() for a
  676.       window controlled by layout.gadget. If successful, this means
  677.       that the user does not need to click in the gadget before
  678.       typing.
  679.  
  680.       The gadget parameter MUST point to the root layout gadget in
  681.       the window, and the object parameter to the gagdet you wish
  682.       to activate. This works by calling the private
  683.       LAYOUT_ACTIVATEOBJECT method to search the layout hierarchy for
  684.       the specified gadget, and set the handleinput path to that
  685.       gadget, and finally calling ActivateGadget for the root object.
  686.  
  687.       The rules of calling ActivateGadget() apply to
  688.       ActivateLayoutGadget() also.
  689.  
  690.   INPUTS
  691.       Gadget = pointer to the root layout obejct for the window.
  692.       Window = pointer to the window the gadget is in.
  693.       Requester = pointer to a requester (may be NULL)
  694.       Object = pointer to the BOOPSI object you wish to activate.
  695.  
  696.   RESULT
  697.       If the conditions above (and those of ActivateGadget()) are
  698.       met, the function will return TRUE, else FALSE.
  699.  
  700.   NOTES
  701.       Not only string gadgets can be activated this way. Many
  702.       ReAction gadget classes, such as the button.gadget, also
  703.       support keyboard control, and thus may be activated this way.
  704.  
  705.       An attempt to activate a gadget that is not currently visible
  706.       (as on a hidden page) will fail.
  707.  
  708.   SEE ALSO
  709.       intuition.library/ActivateGadget()
  710. layout_gc/FlushLayoutDomainCache             layout_gc/FlushLayoutDomainCache
  711.  
  712.   NAME
  713.       FlushLayoutDomainCache -- Flush layout domain cache below a level.
  714.  
  715.   SYNOPSIS
  716.       FlushLayoutDomainCache( layout )
  717.                               a0
  718.  
  719.       void FlushLayoutDomainCache( struct Gadget * )
  720.  
  721.   FUNCTION
  722.       Layout gadget normally caches GM_DOMAIN results from the child
  723.       objects to speed up window re-layout. However, on some rare
  724.       occassions a gadget's minimum or maximum domain might change
  725.       after creation. For these instances layout gadget provides two
  726.       methods of controlling the domain cache. You can set a caching on
  727.       a child-by-child basis, using the CHILD_CacheDomain attribute, so
  728.       that on each relayout the domain is calculated again. This
  729.       method might have an extra performance hit, if the domain
  730.       changes infrequently. It also has to be set for each parent
  731.       layout level, which makes the amount of extra calculations grow
  732.       quickly. The other method, for the cases where the application
  733.       will know when a gadget's domain changes, it can call
  734.       FlushLayoutDomainCache() with a pointer to the parent layout object.
  735.       This call will flush the whole hierarchy, so that the next window
  736.       re-layout will re-calculate child domains.
  737.  
  738.   INPUTS
  739.       layout = the layout object to flush. This should be the topmost
  740.                   layout object for the window.
  741.  
  742.   SEE ALSO
  743.       --datasheet-- (CHILD_CacheDomain attribute)
  744. layout_gc/LAYOUT_GetClass                           layout_gc/LAYOUT_GetClass
  745.  
  746.   NAME
  747.       LAYOUT_GetClass -- Gets the pointer to the layout class.
  748.  
  749.   SYNOPSIS
  750.       layout_class = LAYOUT_GetClass();
  751.       D0
  752.  
  753.       Class * LAYOUT_GetClass(VOID);
  754.  
  755.   FUNCTION
  756.       Obtains the pointer to the layout gadget class for use with
  757.       NewObject().  This function always returns a valid pointer so
  758.       you do not need to check it.  The reason is that if the library
  759.       opens fine, then the pointer returned is already setup.  (Of
  760.       course this implies that if opening the library fails, you
  761.       shouldn't be calling this.)
  762.  
  763.       Note that this function does not create the class, that is done
  764.       when the class library is opened.
  765.  
  766.   INPUTS
  767.       Nothing.
  768.  
  769.   RESULT
  770.       LayoutClass - Pointer to the layout gadget class.
  771. layout_gc/LayoutLimits                                 layout_gc/LayoutLimits
  772.  
  773.   NAME
  774.       LayoutLimits -- easy way to find out max and min size of layout
  775.  
  776.   SYNOPSIS
  777.       LayoutLimits( layout, limits, font, screen );
  778.                     a0      a1      a2    a3
  779.  
  780.       void LayoutLimits( struct Gadget *, struct LayoutLimits *,
  781.                               struct TextFont *, struct Screen * )
  782.  
  783.   FUNCTION
  784.       This function is an easy way of getting the minimum and maximum
  785.       limit of the layout group. Effectively it create a RastPort and
  786.       execute the GM_DOMAIN method for both minimum and maximum size
  787.       of the object filling in the LayoutLimits structure with the size
  788.       values. The font passed to this call will most likely affect the
  789.       results, so use the font you will use with the window. If you
  790.       pass a NULL for the font, the system default font (monospaced)
  791.       will be used. If you pass the optional screen pointer, the
  792.       gadget will be provided a DrawInfo. This will let the gadget
  793.       adjust to the aspect ratio of the screen.
  794.  
  795.       If you use the resulting size for OpenWindow() or WindowLimits(),
  796.       remember that the results do not include window borders.
  797.  
  798.   INPUTS
  799.       layout = the layout object to get the size on.
  800.       limits = a pointer to the struct LayoutLimits to fill.
  801.       font = the TextFont to use on the domain requests. May be NULL
  802.               for system default font.
  803.       screen = optional pointer to the screen on which the layout
  804.               will be used on, or NULL.
  805.  
  806.   NOTES
  807.       This function will invoke the object's GM_DOMAIN method twice,
  808.       with a NULL GadgetInfo. If you call it providing a screen
  809.       pointer, the taglist of the message will contain that screen's
  810.       DrawInfo (GA_DrawInfo) for aspect information.
  811.  
  812.   SEE ALSO
  813.       gadgetclass/GM_DOMAIN
  814. layout_gc/RethinkLayout                               layout_gc/RethinkLayout
  815.  
  816.   NAME
  817.       RethinkLayout -- Relayout and render the layout. (V39)
  818.  
  819.   SYNOPSIS
  820.       RethinkLayout( layout, window, requester, refresh );
  821.                       a0        a1        a2
  822.  
  823.       void RethinkLayout( struct Gadget *, struct Window *,
  824.                               struct Requester *, BOOL )
  825.  
  826.   FUNCTION
  827.       Relayout and refresh the layout page. Call this function after
  828.       a call SetGadgetAttrs() returns 1 to display the changes in the
  829.       layout.  According to BOOPSI rules, a gadget will return a value
  830.       of 1 from OM_SET to tell the application to refresh. This is what
  831.       this function is for. Basically, it will call the GM_LAYOUT and
  832.       GM_RENDER methods of the layout.
  833.  
  834.   INPUTS
  835.       layout = the layout to refresh. Doesn't have to be the topmost
  836.                   object in the hierarchy, if the changes do not affect
  837.                   it.
  838.       window = the window to which the layout (or its parent) is
  839.                   attached to.
  840.       requester = the window's requester, or NULL.
  841.       refresh = whether layout.gadget should also refresh the display.
  842.  
  843.   NOTES
  844.       This function emulates a DoGadgetMethod() on V37 and V38 systems.
  845.  
  846.       The refresh flag is provided for several reasons. First, when using
  847.       LAYOUT_DeferLayout, you should not refresh upon receiving a
  848.       LAYOUT_RequestLayout notification. Second, datatypes have an
  849.       asynchronous layout, and should not be attempted to refresh before
  850.       that is finished. Wait for DTA_Sync, and then RefreshGList( layout,
  851.       window, requester, 1 ).
  852.  
  853.   SEE ALSO
  854.       intuition.library/RefreshGList(), intuition.library/SetGadgetAttrsA(),
  855.       intuition.library/DoGadgetMethod()
  856.